<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>GoJS Introduction -- Northwoods Software</title>
  <!-- Copyright 1998-2016 by Northwoods Software Corporation. -->
  <script src="go.js"></script>
  <script src="goIntro.js"></script>

</head>
<body onload="goIntro()">
  <div id="container" class="container-fluid">
<div id="content">

  <h1>Introduction to GoJS Diagramming Components</h1>

  <p>
  <b>GoJS</b> is a JavaScript library that lets you easily create interactive diagrams in modern web browsers.
  <b>GoJS</b> supports graphical templates and data-binding of graphical object properties to model data.
  You only need to save and restore the model, consisting of simple JavaScript objects holding
  whatever properties your app needs.
  Many predefined tools and commands implement the standard behaviors that most diagrams need.
  Customization of appearance and behavior is mostly a matter of setting properties.
  </p>

  <h3>A Simple GoJS Diagram</h3>
  <p>
  The following code defines a node template and model data, which produces a small diagram with a handful of nodes and links.
  </p>

  <pre data-language="javascript" id="minimal">
      // For conciseness. See the "Building Parts" intro page for more
      var $ = go.GraphObject.make;

      // the node template describes how each Node should be constructed
      diagram.nodeTemplate =
        $(go.Node, "Auto",  // the Shape automatically fits around the TextBlock
          $(go.Shape, "RoundedRectangle",  // use this kind of figure for the Shape
            // bind Shape.fill to Node.data.color
            new go.Binding("fill", "color")),
          $(go.TextBlock,
            { margin: 3 },  // some room around the text
            // bind TextBlock.text to Node.data.key
            new go.Binding("text", "key"))
        );

      // the Model holds only the essential information describing the diagram
      diagram.model = new go.GraphLinksModel(
      [ // a JavaScript Array of JavaScript objects, one per node;
        // the "color" property is added specifically for this app
        { key: "Alpha", color: "lightblue" },
        { key: "Beta", color: "orange" },
        { key: "Gamma", color: "lightgreen" },
        { key: "Delta", color: "pink" }
      ],
      [ // a JavaScript Array of JavaScript objects, one per link
        { from: "Alpha", to: "Beta" },
        { from: "Alpha", to: "Gamma" },
        { from: "Beta", to: "Beta" },
        { from: "Gamma", to: "Delta" },
        { from: "Delta", to: "Alpha" }
      ]);

      diagram.initialContentAlignment = go.Spot.Center;
      // enable Ctrl-Z to undo and Ctrl-Y to redo
      diagram.undoManager.isEnabled = true;
  </pre>
  <p>This creates the following Diagram:</p>
  <script>goCode("minimal", 400, 150)</script>
  <p>
  You can interact with this diagram in many ways:
  <ul>
    <li>You can select a part by clicking on it.
        Selected nodes are highlighted with an <a>Adornment</a> that is a blue rectangle surrounding the node.
        Selected links are highlighted with a blue line following the path of the link.</li>
    <li>Multiple parts may be selected at once.
        Hold the Shift key down when clicking to add to the selection.
        Hold the Control key down when clicking to toggle whether that part is selected.</li>
    <li>Another way to multi-select is to mouse-down at a point in the background (not on a part), wait a moment, and then drag a box.
        Parts that are in the box when the mouse-up occurs are selected.
        The Shift and Control modifiers work then as well.</li>
    <li>Ctrl-A selects all parts in the diagram.</li>
    <li>Move one or more parts by selecting them and dragging.</li>
    <li>Copying selected parts works with either copy/paste (Ctrl-C/Ctrl-V) or with Ctrl-mouse-drag.</li>
    <li>Delete selected parts with the Delete key.</li>
    <li>If scrollbars are visible or if the whole collection of parts is smaller than the viewable area of the diagram (the "viewport"),
        you can pan the diagram with a mouse-down in the background (not on a part) if you drag without waiting.</li>
    <li>Use the mouse wheel to scroll up and down and Shift-mouse-wheel to scroll left and right.
        Ctrl-mouse-wheel zooms in and out.</li>
  </ul>
  </p>
  <p>
  You can also pan, pinch zoom, select, copy, move, delete, undo, and redo with your fingers on a touch device.
  Most commands that can be invoked from a keyboard can be invoked from the default context menu that you get by pressing your finger and holding it motionless for a moment.
  </p>

  <p>
  What is unique about all of the examples in the documentation is that they are all "live" -- there are no screenshots!
  They are actual <a>Diagram</a>s implemented by the source code shown.
  You can interact with them -- some even display animation.
  </p>

  <p>
  If you'd like to see more examples of what <b>GoJS</b> can do, see the <a href="../samples/index.html" target="samples">GoJS Samples directory</a>.
  To make it easier to search the JavaScript code and documentation or to experiment by modifying the samples, you can download a ZIP file of the
  whole web site for the current version of <b>GoJS</b> from <a href="../index.html">GoJS Home</a>.
  Or you can visit <a href="https://github.com/NorthwoodsSoftware/GoJS">GoJS on GitHub</a>.
  </p>

  <h3>GoJS Concepts</h3>
  <p>
  <a>Diagram</a>s consist of <a>Part</a>s: <a>Node</a>s that may be connected by <a>Link</a>s and that may be grouped together into <a>Group</a>s.
  All of these parts are gathered together in <a>Layer</a>s and are arranged by <a>Layout</a>s.
  </p>

  <p>
  Each diagram has a <a>Model</a> that holds and interprets your application data to determine node-to-node link relationships and
  group-member relationships.
  Most parts are data-bound to your application data.
  The diagram automatically creates a <a>Node</a> or a <a>Group</a> for each data item in the model's <a>Model.nodeDataArray</a>
  and a <a>Link</a> for each data item in the model's <a>GraphLinksModel.linkDataArray</a>.
  </p>

  <p>
  Each <a>Node</a> or <a>Link</a> is normally defined by a template that declares its appearance and behavior.
  Each template consists of <a>Panel</a>s of <a>GraphObject</a>s such as <a>TextBlock</a>s or <a>Shape</a>s.
  There are default templates for all parts, but almost all applications will specify custom templates
  in order to achieve the desired appearance and behavior.
  </p>

  <p>
  The nodes may be positioned manually (interactively or programmatically) or may be arranged automatically by the
  <a>Diagram.layout</a> and by each <a>Group.layout</a>.
  </p>

  <p>
  <a>Tool</a>s handle mouse and keyboard events. Each diagram has a number of tools that perform interactive tasks such as
  selecting parts or dragging them or drawing a new link between two nodes. The <a>ToolManager</a> determines
  which tool should be running, depending on the mouse events and current circumstances.
  </p>

  <p>
  Each diagram also has a <a>CommandHandler</a> that implements various commands, such as Delete or Copy.
  The CommandHandler interprets keyboard events, such as control-Z, when the ToolManager is running.
  </p>

  <p>
  The diagram provides the ability to scroll the parts of the diagram and to zoom in or out.
  The diagram also contains all of the layers, which in turn contain all of the parts (nodes and links).
  The parts in turn are composed of possibly nested panels of text, shapes, and images.
  This hierarchy of JavaScript objects in memory forms the "visual tree" of everything that may be drawn by the diagram.
  </p>

  <p>
  The <a>Overview</a> control allows the user to see the whole model and to control what part of it that the diagram displays.
  The <a>Palette</a> control holds parts that the user may drag-and-drop into a diagram.
  </p>

  <p>
  You can select one or more parts in the diagram. The template implementation may change the appearance
  of the node or link when it is selected. The diagram may also add <a>Adornment</a>s to indicate selection and to
  support tools such as resizing a node or reconnecting a link.
  Adornments are also how tooltips and context menus are implemented.
  </p>

  <p>
  All programmatic changes to <a>Diagram</a>, <a>GraphObject</a>, <a>Model</a> or model data state should be performed
  within a single transaction per user action, to make sure updating happens correctly and to support undo/redo.
  All of the predefined tools and commands perform transactions, so each user action is automatically undoable
  if the <a>UndoManager</a> is enabled.
  <a>DiagramEvent</a>s on Diagrams, and event handlers on Diagrams and GraphObjects,
  are all documented whether they are raised within a transaction or whether you need to conduct a transaction in order
  to change the model or the diagram.
  </p>


  <h3>Creating a Diagram</h3>
  <p>
  Before you can execute any JavaScript code to build a Diagram, you will need to load the <b>GoJS</b> library, "go.js".
  When you include the library, the "<code>go</code>" JavaScript object will hold all of the <b>GoJS</b> types.
  During development we recommend that you load "go-debug.js" instead of "go.js", for additional run-time error checking and debugging ability.
  </p>
  <p>
  <b>GoJS</b> does not depend on any JavaScript library or framework, so you should be able to use it in any environment.
  However it does require that the environment support modern HTML and JavaScript, so we recommend that you
  declare that your web page supports modern HTML:
  </p>
  <pre>
  &lt;!DOCTYPE html&gt;  &lt;!-- Declare standards mode. --&gt;
  &lt;html&gt;
    &lt;head&gt;
    . . .
    &lt;!-- Include the GoJS library. --&gt;
    &lt;script src="go.js"&gt;&lt;/script&gt;
  </pre>
  <p>
  If you are using <a href="http://requirejs.org" target="_blank">RequireJS</a>, <b>GoJS</b> supports AMD module definitions.
  See the <a href="../samples/require.html" target="samples">Require sample</a> for an example.
  </p>

  <p>
  Every <a>Diagram</a> must be hosted by an HTML Div element.
  <b>GoJS</b> will manage the contents of that Div element, but you may position and size and style the Div as you would any HTML element.
  The diagram will add a Canvas element to that Div element that the diagram will draw in -- this is what users actually see.
  The Canvas element is automatically sized to have the same size as the Div element.
  </p>

  <pre>
  &lt;body&gt;
    . . .
    &lt;!-- The DIV for a Diagram needs an explicit size or else we won't see anything.
         In this case we also add a border to help see the edges. --&gt;
    &lt;div id="myDiagramDiv" style="border: solid 1px blue; width:400px; height:150px"&gt;&lt;/div&gt;
  </pre>
  <div id="myDiagramDiv" style="border: solid 1px blue; width:400px; height:150px"></div>

  <p>
  Then you can create the <a>Diagram</a> in JavaScript with a reference to that Div element.
  Build the diagram by constructing plain JavaScript objects and adding them to the diagram's model.
  Note that all references in JavaScript code to <b>GoJS</b> types such as <a>Diagram</a> are prefixed with "<code>go.</code>".
  </p>
  <pre>
  &lt;!-- Create the Diagram in the DIV element using JavaScript. --&gt;
  &lt;!-- The "go" object is the "namespace" that holds all of the GoJS types. --&gt;
  &lt;script&gt;
    var diagram = new go.Diagram("myDiagramDiv");
    diagram.model = new go.GraphLinksModel(
      [{ key: "Hello" },   // two node data, in an Array
       { key: "World!" }],
      [{ from: "Hello", to: "World!"}]  // one link, in an Array
    );
  &lt;/script&gt;
  </pre>
  <!-- Create the Diagram using JavaScript. -->
  <!-- The "go" object is the "namespace" that holds all of the GoJS types. -->
  <script>
    var diagram = new go.Diagram("myDiagramDiv");
    diagram.model = new go.GraphLinksModel(
      [{ key: "Hello" },
       { key: "World!" }],
      [{ from: "Hello", to: "World!"}]
    );
  </script>

  <p>
  This completes the implementation of the "Hello World!" live diagram that you see above.
  </p>

  <p class="box bg-danger">
  <b>GoJS</b> outputs error or warning messages when something goes wrong.
  When developing with <b>GoJS</b>, be sure to check your browser's developer console for information.
  The "go-debug.js" version of the library contains extra type-checking and error-checking code, and should be used during development.
  The "go.js" version has less error checking, but is faster as a result, and should be used in production.
  </p>

  <p>
  Your JavaScript code should only use properties and methods that are documented in the <a href="../api/index.html">API</a>.
  The <b>GoJS</b> libraries are "minified", so if you look at an instance of a <b>GoJS</b> class in the debugger,
  you will see many one or two letter property names.  All of those are internal names that you should not use.
  At the current time the only one letter property names are "x" and "y" on <a>Point</a>, <a>Rect</a>, <a>Spot</a> and <a>LayoutVertex</a>.
  The only two letter property name is <a>InputEvent.up</a>.
  Otherwise you should not try to use any one or two letter property names on any <b>GoJS</b>-defined objects.
  </p>

  <p class="box bg-danger">
  Do not modify the prototypes of the <b>GoJS</b> classes.<br />
  Only use the properties and methods documented in the <a href="../api/index.html">API</a>.
  </p>

  <p>
  You can also use <a href="http://www.typescriptlang.org/">TypeScript</a> in order to get better "compile-time" type-checking.
  In your TypeScript code, just reference the "goJS.d.ts" definition file for the "go.js" library:
  </p>
  <pre>
  ///&lt;reference path="goJS.d.ts"/&gt;
  </pre>
  If you are using Visual Studio, this definition file also greatly improves Intellisense feedback while editing TypeScript code.

  <p>
  You can see the variety of kinds of diagrams that you can build at <a href="../samples/index.html" target="samples">GoJS Samples</a>.
  </p>
  <p>
  In the next introduction page we discuss <a href="buildingObjects.html">building <b>GoJS</b> Parts and adding them into Diagrams.</a>
  </p>
</div>
</div>
</body>
</html>
